docs: update resource URI and add plugin support by fitzthum · Pull Request #1468 · confidential-containers/guest-components

fitzthum · 2026-05-12T20:33:19Z

Update the resource URI doc and add support for plugins.

Specifically, let's allow the scheme to be something like kbs+plugin://. This seems pretty reasonable and is backwards compatible.

If this looks good, I will add some commits to actually implement the change.

Our resource URI doc is out-of-date. Let's update it to reflect how we actually use resource URIs and to clarify the relationship between resource URIs and the KBS API. This has confused a number of people in the past. Also, let's introduce a mechanism for specifying the plugin in the resource URI. Specifically, let's allow people to specify the plugin in the scheme. Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

Xynnn007 · 2026-05-13T06:40:15Z

+### Repository, Type, and Tag
+
+Currently resource URIs have three levels of identifiers/scope.
+The terms `repository`, `type`, and `tag` are somewhat arbitrary. 
+These identifiers can be used in any way.


It's resource plugin-specific and no requirements on other plugins

yeah, I was also thinking whether it is a good idea to require the same path segment for every plugin, for some this hierarchy might just not make any sense. but it keeps implementation complexity at bay for now and that requirement can be relaxed later once it becomes a nuisance

Yes - and there is already some implementations that do not follow this, e.g. pkcs11

Yes, we need to clarify this. Currently you cannot access the pkcs11 plugin via the resource uri, which is essentially a bug imo. I am open to allowing arbitrary length requests, like we do with rv uris, but that is not how the resource uri works today.

Xynnn007 · 2026-05-13T06:40:30Z

+A Resource URI must comply with the following format:
+
+```plaintext
+kbs+<plugin>://<kbs_host>:<kbs_port>/<repository>/<type>/<tag>


I like this design

The asymmetry here is that with kbs+<plugin>:// callers need to know the resource is provided by <plugin> but with the resource plugin, they have no way to say the resources comes from vault.

How the plugin URIs can be supported with api-server-rest queries?

vault is not a plugin level conception, but a resource plugin level. Thus it's expected that the caller does not know that.

for ASR, currently is 127.0.0.1:8006/cdh/resource/.... we could generize it as 127.0.0.1:8006/cdh/<plugin-in-name>/... for kbs+<plugin-in-name>:///...

I would also that the caller doesn't get to request a concrete backing store for their resource is (say, vault or filesystem), this is up to the KBS, no?

I also like this URI scheme 👍

vault is not a plugin level conception, but a resource plugin level.

yup, my comment was just that the implementation detail is visible to the user and they don't necessarily understand: why kbs+pcks11:// is needed but kbs+vault:// is not.

the pkcs11 apis are different from the vaults. see https://github.com/confidential-containers/trustee/blob/main/kbs/src/plugins/implementations/pkcs11.rs#L135 for example wrap-key

yeah, also worth noting that the resource plugin only supports one storage backend anyway.

mkulke · 2026-05-13T09:36:54Z

+A Resource URI must comply with the following format:
+
+```plaintext
+kbs+<plugin>://<kbs_host>:<kbs_port>/<repository>/<type>/<tag>


I would also that the caller doesn't get to request a concrete backing store for their resource is (say, vault or filesystem), this is up to the KBS, no?

I also like this URI scheme 👍

mkulke · 2026-05-13T09:43:28Z

+### Repository, Type, and Tag
+
+Currently resource URIs have three levels of identifiers/scope.
+The terms `repository`, `type`, and `tag` are somewhat arbitrary. 
+These identifiers can be used in any way.


yeah, I was also thinking whether it is a good idea to require the same path segment for every plugin, for some this hierarchy might just not make any sense. but it keeps implementation complexity at bay for now and that requirement can be relaxed later once it becomes a nuisance

Xynnn007 · 2026-05-14T01:44:56Z

+
+* `kbs://example.cckbs.org:8081/alice/decryption-key/1`
+* `kbs:///a/b/c`
+* `kbs+pkcs11:///a/b/c`


btw the original resource URI could also support query string, like kbs+plugin1://a/b/c?d=e

Xynnn007 · 2026-05-14T01:47:34Z

btw, confidential-containers/trustee#1305 needs POST and DELETE method. So the concrete implementation should care about this.

fitzthum · 2026-05-14T21:06:47Z

Added implementation. PTAL

note that I am not touching the ASR in this PR. We will still have a gap there. Currently you can make a request via the ASR like this

curl http://127.0.0.1:8006/cdh/resource/default/key/1

I don't think we can make that work with plugins so probably we should add a new endpoint like

curl http://127.0.0.1:8006/cdh/plugin/<plugin-name>/a/b/c

But that is still a bit limited. Open to suggestions here. Probably will address in a follow-up rather than this one.

Xynnn007 · 2026-05-15T01:26:01Z

curl http://127.0.0.1:8006/cdh/plugin//a/b/c

A naive question without a deep dive and implementation experience: what's the blocker to use curl http://127.0.0.1:8006/cdh/<plugin-name>/a/b/c ?

Xynnn007

great work for extension! First round review

Xynnn007 · 2026-05-15T01:28:38Z

+            Some(plugin_name.to_string())
+        } else {
+            return Err("scheme must be kbs or kbs+<plugin>");
+        };


Just a nit

let plugin = match scheme.as_str() { SCHEME => None, s if s.starts_with("kbs+") => { let plugin_name = s.trim_start_matches("kbs+"); if plugin_name.is_empty() { return Err("scheme kbs+ requires a plugin name, e.g. kbs+pkcs11"); } Some(plugin_name.to_string()) } _ => return Err("scheme must be kbs or kbs+<plugin>"), };

Xynnn007 · 2026-05-15T01:29:53Z

    pub r#type: String,
    pub tag: String,
    pub query: Option<String>,
+    pub plugin: Option<String>,


Maybe we can directly set this as String, and give a default resource if none is given

That makes it a little tricky to reconstruct the URI in the whole_uri method. wdyt?

Xynnn007 · 2026-05-15T01:31:02Z

        assert_eq!(resource_from_url, resource);
    }
+
+    #[test]


Can we combine them into a single test with rstest? which will look dry

Xynnn007 · 2026-05-15T01:33:32Z

    /// at CDH startup).
    async fn get_kid(kid: &String) -> Result<Vec<u8>> {
-        if kid.starts_with("kbs://") {
+        if kid.starts_with("kbs://") || kid.starts_with("kbs+") {


I once gave the suggestion to make the plugin a String in ResourceUri struct in previous commit. If it's adopted, here we can simply use kid.starts_with("kbs+").

btw, kid.starts_with("kbs+") might not be enough, we might still need to judge ://. so probably a simple .contains() or a regex can be used. wdyt?

Ok, instead let me import ResourceUri here and try parsing that way.

Xynnn007 · 2026-05-15T01:33:42Z

                source: source.into(),
            })?
-    } else if key_uri.starts_with("kbs://") {
+    } else if key_uri.starts_with("kbs://") || key_uri.starts_with("kbs+") {


The same question

Xynnn007 · 2026-05-15T01:35:12Z

+    let path = if let Some(rest) = keyid.strip_prefix("kbs://") {
+        rest
+    } else if let Some(pos) = keyid.find("://") {
+        let scheme = &keyid[..pos];
+        if scheme.starts_with("kbs+") {
+            &keyid[pos + 3..]
+        } else {
+            keyid
+        }
+    } else {
+        keyid
+    };


Maybe we can import ResourceUri and parse, then extract repository, .. etc

This function has slightly different behavior than the resource Uri parsing. It allows other schemes and even kids without any scheme. So I don't think it gives us much to use the resource uri crate here.

Xynnn007 · 2026-05-15T01:36:48Z

    pub repository: String,
    pub r#type: String,
    pub tag: String,


Note that due to #1468 (comment), we could combine these fields into a Vec<String> for any length paths? wdyt?

I am open to this but I think we should do another PR for handling the variable length stuff.

fitzthum · 2026-05-15T13:24:35Z

A naive question without a deep dive and implementation experience: what's the blocker to use curl http://127.0.0.1:8006/cdh//a/b/c ?

Risk of collision if we introduce any other CDH endpoints in the future, which we might.

Allow the plugin to be specifid as part of the scheme. For example, kbs+plugin:///a/b/c Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

Xynnn007 · 2026-05-15T14:13:43Z

sounds reasonable. what about to multiplex current resource field to work as the plugin name, s.t. 127.0.0.1:8006/cdh/<plugin name>/...?

Xynnn007 · 2026-05-15T14:18:05Z

well. it is also the same issue

Xynnn007 · 2026-05-15T14:25:02Z

so probably cdh/kbs-plugin/xxx or so is the only choice. for legacy, keep legacy resource without kbs-plugin part. note that imo the prefix kbs- is needed because plugin in CDH can be more than kbs.

I have an impression that we once talked about this, but cannot find the thread.

fitzthum · 2026-05-15T15:37:14Z

Yeah, that seems fine, although it doesn't help use with plugins that have query strings or more arguments. I wonder if there is a way to pass the full resource uri.

Fixup a couple of checks based on the scheme to allow for plugins Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

The keyprovider does some manipulation of the resource uri. Update this so that it will work if the uri specifies a plugin. Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

Allow plugins in the resource uri scheme Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

fitzthum requested a review from a team as a code owner May 12, 2026 20:33

fitzthum marked this pull request as draft May 12, 2026 20:33

Xynnn007 reviewed May 13, 2026

View reviewed changes

mkulke approved these changes May 13, 2026

View reviewed changes

fitzthum mentioned this pull request May 13, 2026

kbs/plugins: add provisioner plugin confidential-containers/trustee#1305

Draft

Xynnn007 reviewed May 14, 2026

View reviewed changes

fitzthum force-pushed the plugin-scheme branch 2 times, most recently from 40bba84 to 6ecaccf Compare May 14, 2026 20:15

fitzthum marked this pull request as ready for review May 14, 2026 21:00

Xynnn007 reviewed May 15, 2026

View reviewed changes

resource-uri: add plugin suppor to resource uri

5da4bc4

Allow the plugin to be specifid as part of the scheme. For example, kbs+plugin:///a/b/c Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

fitzthum force-pushed the plugin-scheme branch from 6ecaccf to 7ae32f9 Compare May 15, 2026 15:41

fitzthum added 3 commits May 15, 2026 08:55

cdh: allow for plugin resource uris

b5424e8

Fixup a couple of checks based on the scheme to allow for plugins Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

keyprovider: make uri handling work with plugins

c7bcb8f

The keyprovider does some manipulation of the resource uri. Update this so that it will work if the uri specifies a plugin. Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

image-rs: fixup resource uri scheme checks

9e7932d

Allow plugins in the resource uri scheme Signed-off-by: Tobin Feldman-Fitzthum <tfeldmanfitz@nvidia.com>

fitzthum force-pushed the plugin-scheme branch from 7ae32f9 to 9e7932d Compare May 15, 2026 15:56

Conversation

fitzthum commented May 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fitzthum May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Xynnn007 May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Xynnn007 commented May 14, 2026

Uh oh!

fitzthum commented May 14, 2026

Uh oh!

Xynnn007 commented May 15, 2026

Uh oh!

Xynnn007 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fitzthum commented May 15, 2026

Uh oh!

Xynnn007 commented May 15, 2026

Uh oh!

Xynnn007 commented May 15, 2026

Uh oh!

Xynnn007 commented May 15, 2026

Uh oh!

fitzthum commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

fitzthum May 13, 2026 •

edited

Loading

Xynnn007 May 13, 2026 •

edited

Loading